5.5 Defining Index Macros

When writing a document with an index you will probably define additional macros which make entries into the index. Let's look at an example.

     \newcommand{\ix}[1]{#1\index{#1}}
     \newcommand{\nindex}[1]{\textit{#1}\index[name]{#1}}
     \newcommand{\astobj}[1]{\index{Astronomical Objects!#1}}

The first macro \ix typesets its argument in the text and places it into the index. The second macro \nindex typesets its argument in the text and places it into a separate index with the tag ‘name’¹. The last macro also places its argument into the index, but as subitems under the main index entry ‘Astronomical Objects’. Here is how to make RefTeX recognize and correctly interpret these macros, first with Emacs Lisp.

     (setq reftex-index-macros
           '(("\\ix{*}" "idx" ?x "" nil nil)
             ("\\nindex{*}" "name" ?n "" nil nil)
             ("\\astobj{*}" "idx" ?o "Astronomical Objects!" nil t)))

Note that the index tag is ‘idx’ for the main index, and ‘name’ for the name index. ‘idx’ and ‘glo’ are reserved for the default index and for the glossary.

The character arguments ?x, ?n, and ?o are for quick identification of these macros when RefTeX inserts new index entries with reftex-index. These codes need to be unique. ?i, ?I, and ?g are reserved for the \index, \index*, and \glossary macros, respectively.

The following string is empty unless your macro adds a superordinate entry to the index key - this is the case for the \astobj macro.

The next entry can be a hook function to exclude certain matches, it almost always can be nil.

The final element in the list indicates if the text being indexed needs to be repeated outside the macro. For the normal index macros, this should be t. Only if the macro typesets the entry in the text (like \ix and \nindex in the example do), this should be nil.

To do the same thing with customize, you need to fill in the templates like this:

     Repeat:
     [INS] [DEL] List:
                 Macro with args: \ix{*}
                 Index Tag      : [Value Menu] String: idx
                 Access Key     : x
                 Key Prefix     :
                 Exclusion hook : nil
                 Repeat Outside : [Toggle]  off (nil)
     [INS] [DEL] List:
                 Macro with args: \nindex{*}
                 Index Tag      : [Value Menu] String: name
                 Access Key     : n
                 Key Prefix     :
                 Exclusion hook : nil
                 Repeat Outside : [Toggle]  off (nil)
     [INS] [DEL] List:
                 Macro with args: \astobj{*}
                 Index Tag      : [Value Menu] String: idx
                 Access Key     : o
                 Key Prefix     : Astronomical Objects!
                 Exclusion hook : nil
                 Repeat Outside : [Toggle]  on (non-nil)
     [INS]

With the macro \ix defined, you may want to change the default macro used for indexing a text phrase (see Creating Index Entries). This would be done like this

     (setq reftex-index-default-macro '(?x "idx"))

which specifies that the macro identified with the character ?x (the \ix macro) should be used for indexing phrases and words already in the buffer with C-c / (reftex-index-selection-or-word). The index tag is "idx".